home *** CD-ROM | disk | FTP | other *** search
/ Compendium Deluxe 1 / LSD Compendium Deluxe 1.iso / a / programming / arexx / arexg10c.lha / ARexxGuide / Extras / ARx_Help.ttx.README < prev    next >
Encoding:
Text File  |  1993-10-16  |  8.2 KB  |  188 lines
  1. Short: TTX help-key macro for ARexxGuide
  2. Author: Robin Evans
  3.  
  4. DESCRIPTION
  5. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  6. This ARexx macro for TurboText must be used in conjunction with
  7. ARexxGuide, a shareware hypertext manual. It gives a quick online
  8. reference to the syntax of ARexx functions and instruction keywords.
  9.  
  10. Pressing the help key when the cursor is positioned on any word or
  11. character with a special meaning in ARexx will bring up an AmigaGuide
  12. window with information about the instruction keyword, function, or
  13. operator character.
  14.  
  15. The library rexxarplib.library may be used with this macro to open a
  16. requester that lists information about a word that is not recognized.
  17.  
  18. rexxarplib.library IS NOT REQUIRED, however. If two comment tokens
  19. are removed from the code, the rexxarplib requester will not be
  20. shown. Instructions for making that alteration are included in the
  21. macro. A stray GetEnv(), that required rexxarplib, has been removed
  22. from version 1.1.
  23.  
  24. VERSION
  25. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  26. Version 1.1
  27.  
  28.    This version has added more error checking than either of the
  29.    previous two versions. It now aborts if the required environmental
  30.    variables are not set.
  31.  
  32.    Those who have things properly set up for the macro may wish to
  33.    delete the lengthy error-checking stuff, which lugs down the
  34.    loading process.
  35.  
  36. REQUIRED FILES
  37. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  38.    ARx_Help.TTX      A TurboText macro. Place in rexx: directory.
  39.    ARx_Guide.xref    An AmigaGuide cross-reference file. Place in
  40.                      directory with other ARexxGuide files.
  41.    TTX_ARexxHelp.dfn A TurboText supplemental definitions file. Place in
  42.                      TurboText:Support directory.
  43.  
  44. OTHER REQUIREMENTS
  45. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  46. The shareware file ARexxGuide is required. It can be found on Aminet
  47. in the util/rexx directory as file name ARexxGuide1_0A.lha.
  48.  
  49. AmigaGuide (available on Aminet) or Multiview is required to run
  50. ARexxGuide.
  51.  
  52. The freeware library rexxarplib.library is useful for this macro, but
  53. not necessary.
  54.  
  55. SETUP:
  56. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  57. Two environmental variables must be set for this file:
  58.  
  59.    amigaguide/path         May include multiple directories, but one
  60.                            of them must be the full path to the
  61.                            directory where ARexxGuide files are
  62.                            located. Without this env: variable, the
  63.                            macro script will not be able to load
  64.                            ARx_Guide.xref. The current version of the
  65.                            script aborts if that happens. Previous
  66.                            versions didn't check. AmigaGuide would
  67.                            sometimes cause gurus since it was sent
  68.                            invalid information.
  69.  
  70.    arexxguide/agcmd        Must hold the command used to start
  71.                            whatever utility will be used to launch
  72.                            the ARexxGuide files. It can include a
  73.                            full path, if necessary. The current
  74.                            version of the script aborts if this
  75.                            variable is not set, but doesn't check for
  76.                            the existence of the command.
  77.  
  78. The macro ARx_Help.TTX should be moved to your REXX: directory. The
  79. file ARx_Guide.xref should be moved to the directory where the other
  80. files in the ARexxGuide archive are stored. There may already be a
  81. file of that name in the directory (it was included in the Extras
  82. drawer of the original archive). This version is more complete and
  83. should replace the original.
  84.  
  85.    TurboText definitions files
  86.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  87. Finally, TurboText must be told about the macro so that you can use
  88. it easily when editing an ARexx script. That is done through one of
  89. TurboText's definitions files, which are located by default in the
  90. TurboText:Support directory. These files allow the user to customize
  91. the way TurboText handles certain keys, menus, and other aspects of
  92. the program. A macro can be attached to any key, for example.
  93.  
  94. Consult the TTX manual, Chapter 9, for more information about
  95. definitions files.
  96.  
  97. The file that is automatically loaded when TurboText begins is called
  98. TTX_Startup.dfn. That file should be changed if you want the
  99. ARexxGuide help key available whenever you run TurboText. It is also
  100. possible to install the help key only when needed. Both methods are
  101. described below:
  102.  
  103.       Automatic help-key
  104.       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  105.    Add the following lines to the section labeled KEYBOARD: in the file
  106.    TTX_Startup.dfn.
  107.  
  108.       HELP               ExecARexxMacro "ARx_Help" SYNC
  109.       SHIFT-HELP         ExecARexxMacro "ARx_Help" ASYNC
  110.  
  111.    You may wish to use another qualifier-key, like CTRL or ALT. The
  112.    wide range of choices for qualifier keys are described in the file
  113.    TTX_Standard.dfn at about line 129.
  114.  
  115.    The parameters 'SYNC' and 'ASYNC' determine how the macro will
  116.    treat previously opened windows under v34 of the AmigaGuide
  117.    utility. If 'SYNC' is specified, the the macro will load the
  118.    current node into a window previously opened by the macro. It will
  119.    bring the window to the front of the screen. The 'ASYNC' options
  120.    causes v34 to open a new window each time the help key is pressed.
  121.  
  122.    A new window is always opened when MultiView is used as the
  123.    display utility since the macro has no way to know if a previous
  124.    window is available.
  125.  
  126.       Explicit loading of help-key definition
  127.       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  128.    If you'd rather not have the help-key defined at all times, you
  129.    can use the file TTX_ARexxHelp.dfn, to define the help key only
  130.    when needed. Place that file in the TurboText:Support directory
  131.    and load it by choosing the menu item Prefs/Open Defs. It will
  132.    alter the current definition for the Help and Shift-Help keys, but
  133.    will not affect other definitions.
  134.  
  135.    To return to the standard definition, choose TTX_Startup.dfn from
  136.    the Prefs/Open Defs menu.
  137.  
  138.  
  139. HOW IT WORKS:
  140. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  141.  
  142.         In the list below the { ^ } character is used to indicate the
  143.         position of the cursor when the help key is pressed. The notes
  144.         after the { :: } characters explain what the macro will display.
  145.  
  146. -------
  147.    if abbrev(strip(upper(Info)), 'SHOW') then  do
  148.  ^
  149.  :: A requester will present information about the clause. It identifies
  150.     the clause as an instruction, assignment, command, comment, or null.
  151. -------
  152.    if abbrev(strip(upper(Info)), 'SHOW') then  do
  153.                                                  ^
  154.  :: The ARexxGuide node for DO will be displayed. If the cursor is located
  155.     at an end-of-line blank, it will look for a node matching the last
  156.     word in the line. It isn't necessary to enter the () after a function
  157.     name to get help for that function. Just type the name and press help.
  158. -------
  159.    if abbrev(strip(upper(Info)), 'SHOW') then  do
  160.        ^
  161.  :: The ARexxGuide node for the ABBREV() function will appear.
  162. -------
  163.    if abbrev(strip(upper(Info)), 'SHOW') then  do
  164.                   ^
  165.  :: The ARexxGuide node explaining parentheses will appear. Generally,
  166.     when the cursor is located on a punctuation mark of some kind, the
  167.     node for that character will appear. This is useful when one wishes to
  168.     check for valid operator characters.
  169. -------
  170.    if abbrev(strip(upper(Info)), 'SHOW') then  do
  171.                            ^
  172.  :: A requester will identify the current clause as an instruction and
  173.     will identify 'Info' as a variable and as a function argument. If a
  174.     lookup word is not recognized as an instruction keyword or subkeyword
  175.     or as a function name, the macro will attempt to identify how the word
  176.     is used in the clause. It recognizes variables, numbers, strings,
  177.     function names, function arguments, and more. It will, however, be
  178.     confused by a clause that includes multiple levels of quotation marks.
  179. --------
  180.    if abbrev(strip(upper(Info)), 'SHOW') then  do
  181.                                    ^
  182.  :: This would normally be identified in a requester as a string, but
  183.     since SHOW() is the name of a built-in macro, the macro won't make it
  184.     that far. It will display the ARexxGuide node for SHOW(). In general,
  185.     the macro will display the node for any word recognized as a function
  186.     or instruction name, even if the word is used in a different context
  187.     in the clause.
  188.